Crate embedded_nal_coap

source ·
Expand description

A CoAP server and client implementation built on embedded_nal_async.

Usage and operation

An example of how to use this will be available as part of the [coap-message-demos] crate.

  • Allocate a CoAPShared with a CONCURRENT_REQUESTS const of the number of outgoing requests that should be servicable simultaneously.

  • CoAPShared::split() that into a client and a server part.

  • Use the client’s CoAPRuntimeClient::to() method to create a coap_request::Stack that can be used to send CoAP requests and receive a response. (Multiple responses, eg. from observation, are planned but not implemented yet).

    The [coap_request_implementations] crate contains suitable (albeit immature) building blocks for constructing requests.

  • Into the server’s CoAPRunner::run() method, pass an unconnected UDP socket, a source of low-grade entropy (for retransmission jitter and that like) and a CoAP server application.

    The [coap_handler_implementations] crate contains suitable building blocks for constructing such a server application (including some to combine handlers for individual resources into a handler that picks sub-handlers from the URI path).

    The future returned by the run function needs to be polled by an executor; note that it is not Send, and some executors need configuration to allow that.

Caveats

  • The server does not perform any amplification mitigation (and the handler can’t for lack of remote information); use this only in environments where this is acceptable (e.g. in closed networks).

    This will be mitigated in a future version.

    FIXME only provide the 3x buffer for responses / when the handler indicates that it needs more, 4.01 Echo? (The handler may be unhappy that it gets dropped; -handlers may need guidance on this)

  • This server does not uphold NSTART and PROBING_RATE, the fundamental flow control parameters of CoAP that make it OK for generic Internet applications.

    This will be addressed in a future version.

    FIXME pass in a time source

  • The server does not perform any message deduplication. All handler functions must therefore be idempotent.

  • Messages are created with as little copying as [embedded_nal] permits. For writable messages, that means that they need to be written to in ascending CoAP option number. This is in accordance with the implemented coap_message::MinimalWritableMessage and coap_message::MutableWritableMessage traits.

    That restriction enables this crate to not only be no_std, but to not require alloc either.

Choices

This implementation of CoAP chooses to go with a single task, thus only ever allocating a single buffer as part of the task. There are certainly alternative choices to be made here, which may either be implemented in a different crate or altered later (for example, if it turns out that a more effective implementation uses different tasks for send and receive, but uses a single buffer or an at-least-1-sized pool that gets locked by the tasks).

Structs

Enums